<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
    <title>CloverValidator User Guide</title>
    <meta http-equiv="Content-Type" content="text/html;Charset=UTF-8">
    <link rel="stylesheet" type="text/css" href="css/styles.css" />
    <link rel="stylesheet" type="text/css" href="css/shCoreEclipse.css" />
    <script type="text/javascript" src="js/shCore.js"></script>
    <script type="text/javascript" src="js/shBrushJScript.js"></script>
    <script type="text/javascript" src="js/shBrushXml.js"></script>

</head>
<body>
<div id="wrapper">
<div id="content">
<h1>Clover Tools - Validator 用户手册</h1>
<div class="section">
    <h2>基本使用</h2>
    <p>要进行简单的表单验证非常容易，例如有如下表单：</p>
            <pre class="brush: html">
                &lt;form id=&quot;userForm&quot;&gt;
                    &lt;label&gt;用户名&lt;input type=&quot;text&quot; name=&quot;username&quot; title=&quot;用户名&quot;/&gt;&lt;/label&gt;
                    &lt;label&gt;密码&lt;input type=&quot;password&quot; name=&quot;password&quot; title=&quot;密码&quot;/&gt;&lt;/label&gt;
                    &lt;label&gt;生日&lt;input type=&quot;text&quot; name=&quot;birthday&quot; title=&quot;生日&quot;/&gt;&lt;/label&gt;
                    &lt;label&gt;
                        学历
                        &lt;select name=&quot;education&quot; title=&quot;学历&quot;&gt;
                            &lt;option value=&quot;-1&quot;&gt;--请选择--&lt;/option&gt;
                            &lt;option value=&quot;初中&quot;&gt;初中&lt;/option&gt;
                            &lt;option value=&quot;高中&quot;&gt;本科&lt;/option&gt;
                            &lt;option value=&quot;本科&quot;&gt;本科&lt;/option&gt;
                            &lt;option value=&quot;硕士&quot;&gt;硕士&lt;/option&gt;
                        &lt;/select&gt;
                    &lt;/label&gt;
                &lt;/form&gt;
            </pre>
    <p>对上面的表单进行一些简单的基础校验，可按下方的方式编写：</p>
            <pre class="brush: js">
                var validator = new Clover.validator.Validator("#userForm");   //创建Validator
                validator.addValidation("[name='username']", "required");    //为username添加必填验证
                validator.addValidation("[name='username']", "Chinese");     //为username添加中文验证
                validator.addValidation("[name='password']", "required");    //为password添加必填验证
                validator.addValidation("[name='password']", "length>6", "密码长度必须大于6位");    //为password添加长度验证,并添加自定义信息
                validator.addValidation("[name='password']", "alpha");       //为password添加字符验证,只能包含字母,数字及下划线
                validator.addValidation("[name='birthday']", "date");        //为birthday添加日期验证
                validator.addValidation("[name='education']", "required");     //为education添加必选验证
            </pre>
    <dl>
        <dt>var validator = new Clover.validator.Validator(jQuery选择器, [选项]);</dt>
        <dd>创建Clover.validator.Validator对象的参数是可选的，第一个参数为jQuery选择器。选择器的目标一般应为form元素，但并不强制。</dd>
        <dd>选项为可选参数，涉及的选项有是否自动绑定form元素的提交事件、以什么方式显示错误信息等，一般情况下使用默认即可，详细请查看API文档。</dd>
    </dl>
    <dl>
        <dt>validator.addValidation(jQuery选择器, 验证表达式, [自定义错误信息])</dt>
        <dd>添加一个验证，参数有三个，前两个为必填，第三个“自定义错误信息可选”。</dd>
        <dd>第一个参数为jQuery选择器。</dd>
        <dd>
            第二个参数为验证表达式或正则表达式，或一个函数对象。验证表达式一般为验证类型的名字，即上述举例的那些“必填”，“中文”，“时间”等，一些验证类型可携带参数，例如例子当中的“length>6”。该框架以内置了很多常用的验证类型，
            要查看所有内置的验证类型，请点击<a href="#innerValidation">这里</a>。
        </dd>
        <dd>第三个参数为自定义错误信息，即验证不通过时的反馈信息，该参数为可选参数。当不填写的时候使用默认的错误信息。当填写该参数时即使用该信息作为反馈信息。</dd>
    </dl>
    <p>给出第二个参数为正则表达式和自定义函数的例子</p>
    <pre class="brush: js">
        validator.addValidation("#password_confirm", function (target) {
            return target.val() == $("#password").val();
        }, "两次输入的密码不相同");

        validator.addValidation("#code", /^#/, "编码必须以#号开头");
    </pre>
    <dl>
        <dt>validator.validate()</dt>
        <dd>
            执行验证。返回值为Boolean类型，为true时表示验证通过，为false时表示验证不通过。
            一般在clover.validator.Validator()的构造方法中传入了form元素的情况下会自动在提交时触发，不需要手动执行。
        </dd>
    </dl>
    <p><span class="important">Validator的创建应该在一个onload事件中。</span>
        创建Validator的时候，如果是写在head部分，那么应该在一个onload事件中，否则应该在页面的最下面。框架提供了一个添加onload事件的方法。
    </p>
    <pre class="brush: js">
        $(function () {
            var validator = new Clover.validator.Validator("TestForm");
            validator.addValidation("#username", "required");
            validator.addValidation("#password", "required");
        });
    </pre>
</div>
<div class="section">
    <h2><a name="defaultValidation">条件验证</a></h2>
    <p>有时会遇到一些满足一定条件才触发验证的需求，例如下面的表单：</p>
            <pre class="brush: html">
                兴趣：
                <label><input type="checkbox" name="favor" value="music" />音乐</label>
                <label><input type="checkbox" name="favor" value="movie" />电影</label>
                <label><input type="checkbox" name="favor" value="animation" />动画</label>
                <label><input type="checkbox" name="favor" value="book" />读书</label>
                <label><input type="checkbox" name="favor" value="other" />其他</label>
                <label>其他：<input type="text" name="other_favor" /></label>
            </pre>
    <p>你可能希望当用户勾选了“其他”时填写“其他(other_favor")”字段，那么你可以使用addConditionalValidation方法，如下：</p>
            <pre class="brush: js">
                validator.addConditionalValidation("[name='other_favor']", "required", "[name='favor']", "include=other", "请填写其他兴趣");
            </pre>
    <dl>
        <dt>validator.addConditionalValidation(jQuery选择器, 验证表达式, jQuery选择器, 验证表达式, [自定义错误信息]);</dt>
        <dd>
            可把参数看为两对，前两个参数为一对，第三个和第四个参数为一对，每对都相当于addValidation的前两个参数。第一对为条件触发后进行的验证，
            第二对为触发条件，当第二对验证通过时会执行第一对验证并返回验证结果，如果第二对验证没有通过则忽略第一对验证。
        </dd>
    </dl>
    <p>该方法还有另一种形式</p>
    <dl>
        <dt>validator.addConditionalValidation(jQuery选择器, 验证表达式, 自定义条件函数, [自定义错误信息]);</dt>
        <dd>
            前两个参数与第一种形式类似，第三个参数为一个Function对象，可以编写任何你想要的逻辑，最后返回Boolean即可，true表示应该执行验证，
            false表示应忽略该验证。
        </dd>
    </dl>
    <p>例子如下：</p>
    <pre class="brush: js">
        validator.addConditionalValidation("[name='other_favor']", "required", function() {
            return $("#other").prop("checked");
        }, "请填写其他兴趣");
    </pre>
</div>
<div class="section">
    <h2><a name="defaultValidation">验证表达式及内建验证器</a></h2>
    <h3>验证表达式</h3>
    <p>验证表达式有以下几部分组成（“[]”中的内容表示可选部分）：</p>
    <code>[*][!][~]验证器[运算符][参数][[长度,长度]]</code>
    <dl>
        <dt>*</dt>
        <dd>重新获取标识。用于目标有可能发生变化的情况，比如被禁用或被删除、添加等。具有该标识元素每次验证会重新获取元素，并且过滤掉被禁用的元素。如果目标消失，则该验证会永远返回“真”，即忽略该验证。</dd>
        <dt>!</dt>
        <dd>
            相当于内建验证其中的“required”。在验证之前先验证必填，相当于先添加了一个required验证。
        </dd>
        <dt>~</dt>
        <dd>对验证的结果取反。例如"~integer"相当目标中不能为数字。</dd>
        <dt>验证器</dt>
        <dd>即下表所示中的内容。除了内建的验证器以外，用户也可以注册自己的验证器，来满足特殊的需要。</dd>
        <dt>运算符</dt>
        <dd>支持参数的验证器配套使用的运算符，每个验证器支持的运算符都不一定相同。</dd>
        <dt>参数</dt>
        <dd>根据验证器不同，作用不同，详情查看各个验证器的说明。</dd>
        <dt>长度</dt>
        <dd>
            用于添加字符长度范围的验证，可用形式为以下几种：[length]，[lengthLeft,]，[lengthLeft,lengthRight]，[,lengthRight]。分别代表：
            长度=length，长度&ge;lengthLeft，lengthLeft&le;长度&le;lengthRight，长度&le;lengthRight
        </dd>
    </dl>
    <h3><a name="innerValidation">内建验证器</a></h3>
    <table class="s-table">
        <tr>
            <th>验证器类型</th>
            <th>作用</th>
            <th>可应用的标签</th>
            <th>支持的运算符</th>
            <th style="width: 400px;">参数</th>
        </tr>
        <tr>
            <td>required</td>
            <td>必填验证</td>
            <td>textfield, password, textarea, file</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>select</td>
            <td>必选项</td>
            <td>heckbox, radio</td>
            <td> = &gt; &lt; &gt;= &lt;= </td>
            <td>参数为可选，为选项的个数，例如"select>=2"即至少要选择两项</td>
        </tr>
        <tr>
            <td>integer</td>
            <td>内容必须为数字，并且不可为小数</td>
            <td>全部</td>
            <td>=</td>
            <td>参数为可选项，作用是规定整数的最大位数，例如"integer=5"即位数不超过5位的整数</td>
        </tr>
        <tr>
            <td>float</td>
            <td>内容为小数</td>
            <td>全部</td>
            <td>=</td>
            <td>参数为可选项，作用是规定整数部分和小数部分的最大位数。例如"float=10.2"即整数部分不超过10位，小数部分不超过两位</td>
        </tr>
        <tr>
            <td>date</td>
            <td>日期格式，默认为yyyy-MM-dd</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>datetime</td>
            <td>日期时间格式，默认为yyyy-MM-dd HH:mm(:ss)</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>dateOrder</td>
            <td>日期顺序验证</td>
            <td>全部</td>
            <td> = &gt; &lt; &gt;= &lt;= </td>
            <td>
                该参数支持两种类型。一种为格式为“yyyy-MM-dd”的表示日期的字符串。例如"date>2005-5-30"，即目标日期要大于2005年5月30日。
                另一种为另一个表单中的表单元素，该元素的值将作为日期与目标进行比较。例如"date>endDate"，即目标值要大于endDate中的日期 。
            </td>
        </tr>
        <tr>
            <td>email</td>
            <td>邮件格式验证</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>telephone</td>
            <td>电话号码格式验证</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>idCard</td>
            <td>身份证号格式验证</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>ip</td>
            <td>IP地址格式验证</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>url</td>
            <td>URL格式验证</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>alpha</td>
            <td>内容只允许包含大小英文字母，数字以及下划线("_")</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>Chinese</td>
            <td>内容只允许包含中文</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>sqlSensitive</td>
            <td>不允许包含SQL敏感字符，包含 % & * ' = ? +</td>
            <td>全部</td>
            <td>无</td>
            <td>无</td>
        </tr>
        <tr>
            <td>length</td>
            <td>字符长度验证</td>
            <td>全部</td>
            <td> = &gt; &lt; &gt;= &lt;= </td>
            <td>字符长度，例如"length>=6"即内容字符的长度要大于等于6位</td>
        </tr>
        <tr>
            <td>value</td>
            <td>值验证，对填写的具体值进行验证，比如要求填写的值大于100等。</td>
            <td>全部</td>
            <td> = &gt; &lt; &gt;= &lt;= </td>
            <td>进行比对的目标值</td>
        </tr>
        <tr>
            <td>include</td>
            <td>选中值验证，检测用户是否选中了checkbox， radio中的某些选项。该验证一般用于条件验证时使用</td>
            <td>checkbox, radio</td>
            <td>=</td>
            <td>包含的值</td>
        </tr>
    </table>
</div>
<div class="section">
    <h2>异步验证</h2>
    <p>很多时候，验证需要与后台交互才可完成，这种情况下，验证需要异步的进行使用以下方法</p>
    <pre class="brush: js">
        validation.addAsyncValidation("#username", function (target, informer) {
            $.getJson("/isValidaUsername.action", {username: target.val()}, function (isValid) {
                informer(isValid);
            };
        }, "用户名已存在");
    </pre>
    <dl>
        <dt>validation.addAsyncValidation(jQuery选择器, 处理函数, 错误信息);</dt>
        <dd>第一个参数为jQuery选择器。</dd>
        <dd>
            第二个参数为处理函数，处理函数接受两个参数，第一个参数为受检目标的jQuery包装对象,在上例中即相当于$("#username")。
            第二个参数为通知函数，通知验证器最后验证的结果，接受一个Boolean类型的值，true表示验证通过。
        </dd>
        <dd>
            第三个参数为错误信息，该处错误信息为必选参数。
        </dd>
    </dl>
</div>
<div class="section">
    <h2>错误信息的显示</h2>
    <p>错误信息的显示目前有两种形式，Tooltip提示及Alert提示两种，未来还会添加更多展现形式。选择不同的展现形式需要在构造验证器的构造函数中传递想要的渲染器。</p>
    <p><strong>Tooltip：</strong>Clover.validator.TipMessageRenderer</p>
    <p><strong>Alert：</strong>Clover.validator.AlertMessageRenderer</p>
    <pre class="brush: js">
        var validator = new Clover.validator.Validator("#targetForm", {
            renderer: Clover.validator.TipMessageRenderer,
            validateOnChange: true,
            showAllMessage: true,
        });
    </pre>
    <dl>
        <dt>renderer</dt>
        <dd>使用哪个渲染器。</dd>
        <dt>validateOnChange</dt>
        <dd>是否在表单元素change事件发生时进行验证。</dd>
        <dt>showAllMessage</dt>
        <dd>是否显示全部错误。当为false时，无论有多少条错误信息，只显示第一条。</dd>
    </dl>
</div>
</div>
<div class="section">
    <h2>自动加载验证</h2>
    <p>添加clover_validator_3.0.autoload.js后可实现自动扫描页面，自动添加验证的功能，目前该功能还比较简单，每个表单元素只能添加一个验证。
        <span class="important">该功能需要jQuery 1.5或以上版本的支持。</span>
    </p>
    <pre class="brush: html">
        &lt;form id=&quot;userForm&quot; class=&quot;validation-required&quot;&gt;
            &lt;label&gt;用户名&lt;input type=&quot;text&quot; data-validation=&quot;!Chinese&quot; name=&quot;username&quot; title=&quot;用户名&quot;/&gt;&lt;/label&gt;
            &lt;label&gt;密码&lt;input type=&quot;password&quot; data-validation=&quot;!alpha&quot; name=&quot;password&quot; title=&quot;密码&quot;/&gt;&lt;/label&gt;
            &lt;label&gt;生日&lt;input type=&quot;text&quot; data-validation=&quot;date&quot; name=&quot;birthday&quot; title=&quot;生日&quot;/&gt;&lt;/label&gt;
            &lt;label&gt;
                学历
                &lt;select name=&quot;education&quot; data-validation=&quot;required&quot; title=&quot;学历&quot;&gt;
                    &lt;option value=&quot;-1&quot;&gt;--请选择--&lt;/option&gt;
                    &lt;option value=&quot;初中&quot;&gt;初中&lt;/option&gt;
                    &lt;option value=&quot;高中&quot;&gt;本科&lt;/option&gt;
                    &lt;option value=&quot;本科&quot;&gt;本科&lt;/option&gt;
                    &lt;option value=&quot;硕士&quot;&gt;硕士&lt;/option&gt;
                &lt;/select&gt;
            &lt;/label&gt;
        &lt;/form&gt;
    </pre>
    <p>
        在需要自动添加验证的form上添加class：“validation-required”，该form下所有带有“data-validation”属性的表单元素都会自动添加验证。
        如果需要添加自定义的错误信息，可在对应的表单元素上添加“data-message”属性。
        <span class="important">自动添加验证的表单仅限页面中初始就存在的表单，由DOM编程方式后添加到页面中的表单不会自动被添加验证。</span>
    </p>
</div>
</div>

<script type="text/javascript">
    SyntaxHighlighter.all();
</script>
</body>
</html>